IDLWAVE User Manual: Routine Info

4.2 Routine Info

IDL comes bundled with more than one thousand procedures, functions and object methods, and large libraries typically contain hundreds or even thousands more (each with a few to tens of keywords and arguments). This large command set can make it difficult to remember the calling sequence and keywords for the routines you use, but IDLWAVE can help. It builds up routine information from a wide variety of sources; IDLWAVE in fact knows far more about the ‘.pro’ routines on your system than IDL itself! It maintains a list of all built-in routines, with calling sequences and keywords². It also scans Emacs buffers for routine definitions, queries the IDLWAVE-Shell for information about routines currently compiled there, and automatically locates library and user-created catalogs. This information is updated automatically, and so should usually be current. To force a global update and refresh the routine information, use C-c C-i (idlwave-update-routine-info).

To display the information about a routine, press C-c ?, which calls the command idlwave-routine-info. When the current cursor position is on the name or in the argument list of a procedure or function, information will be displayed about the routine. For example, consider the indicated cursor positions in the following line:

plot,x,alog(x+5*sin(x) + 2),
  |  |   |   |   |  |  |    |
  1  2   3   4   5  6  7    8

On positions 1,2 and 8, information about the ‘plot’ procedure will be shown. On positions 3,4, and 7, the ‘alog’ function will be described, while positions 5 and 6 will investigate the ‘sin’ function.

When you ask for routine information about an object method, and the method exists in several classes, IDLWAVE queries for the class of the object, unless the class is already known through a text property on the ‘->’ operator (see Object Method Completion and Class Ambiguity), or by having been explicitly included in the call (e.g., a->myclass::Foo).

The description displayed contains the calling sequence, the list of keywords and the source location of this routine. It looks like this:

Usage:    XMANAGER, NAME, ID
Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER
          JUST_REG MODAL NO_BLOCK
Source:   SystemLib   [LCSB] /soft1/idl53/lib/xmanager.pro

If a definition of this routine exists in several files accessible to IDLWAVE, several ‘Source’ lines will point to the different files. This may indicate that your routine is shadowing a system library routine, which may or may not be what you want (see Load-Path Shadows). The information about the calling sequence and keywords is derived from the first source listed. Library routines are available only if you have scanned your local IDL directories or are using pre-scanned libraries (see Catalogs). The source entry consists of a source category, a set of flags and the path to the source file. The following default categories exist:

System	A system routine of unknown origin. When the system library has been scanned as part of a catalog (see Catalogs), this category will automatically split into the next two.
Builtin	A builtin system routine with no source code available.
SystemLib	A library system routine in the official lib directory `!DIR/lib`.
Obsolete	A library routine in the official lib directory `!DIR/lib/obsolete`.
Library	A routine in a file on IDL’s search path `!PATH`.
Other	Any other routine with a file not known to be on the search path.
Unresolved	An otherwise unknown routine the shell lists as unresolved (referenced, but not compiled).

Any routines discovered in library catalogs (see Library Catalogs), will display the category assigned during creation, e.g., ‘NasaLib’. For routines not discovered in this way, you can create additional categories based on the routine’s filename using the variable idlwave-special-lib-alist.

The flags [LCSB] indicate the source of the information IDLWAVE has regarding the file: from a library catalog ([L---] ), from a user catalog ([-C--], from the IDL Shell ([--S-] ) or from an Emacs buffer ([---B]). Combinations are possible (a compiled library routine visited in a buffer might read [L-SB] ). If a file contains multiple definitions of the same routine, the file name will be prefixed with ‘(Nx)’ where ‘N’ is the number of definitions.

Some of the text in the *Help* routine info buffer will be active (it is highlighted when the mouse moves over it). Typically, clicking with the right mouse button invokes online help lookup, and clicking with the middle mouse button inserts keywords or visits files:

Usage	If online help is installed, a click with the right mouse button on the Usage: line will access the help for the routine (see Online Help).
Keyword	Online help about keywords is also available with the right mouse button. Clicking on a keyword with the middle mouse button will insert this keyword in the buffer from where `idlwave-routine-info` was called. Holding down `SHIFT` while clicking also adds the initial ‘`/`’.
Source	Clicking with the middle mouse button on a ‘`Source`’ line finds the source file of the routine and visits it in another window. Another click on the same line switches back to the buffer from which `C-c ?` was called. If you use the right mouse button, the source will not be visited by a buffer, but displayed in the online help window.
Classes	The Classes line is only included in the routine info window if the current class inherits from other classes. You can click with the middle mouse button to display routine info about the current method in other classes on the inheritance chain, if such a method exists there.

User Option: idlwave-resize-routine-help-window (t): Non-nil means resize the Routine-info *Help* window to fit the content.

User Option: idlwave-special-lib-alist: Alist of regular expressions matching special library directories.

User Option: idlwave-rinfo-max-source-lines (5): Maximum number of source files displayed in the Routine Info window.

Footnotes

(2)

This list is created by scanning the IDL manuals and might contain (very few) errors. Please report any errors to the maintainer, so that they can be fixed.